Skip to main content

Terminal Registration

Before a terminal can be used to send transactions to the TPS, it must first be registered in TPS.

Terminal registration process depends from the terminal activation type. The following activation types are possible:

  • No activation. Used for terminals that don't use Sfey terminal management system for key management.
  • HCV activation. Used for terminals that don't have Device HSM CA Certificate preloaded.
  • Automatic activation. Used for terminals that have Device HSM CA Certificate preloaded.

Terminal registration consists of the following steps:

  1. Describing terminal in TPS. The terminal is described in TPS by Sfey support, for this you need to provide the following terminal data:
    • organization under which the terminal is used
    • terminal type
    • terminal serial number
  2. Terminal registration. Once the terminal is described in TPS, the terminal must first send a Terminal Registration request to TPS.
  3. Terminal activation. Only applicable for terminals using HCV activation. After the registration is done, the terminal should be manually activated via TPS Payments Manager.

Terminal configuration​

The Terminal should keep the following information in its local storage.

Registration information​

The Terminal should manage the keys and certificates as described there:

During the terminal registration process terminal receives the following information from TPS:

  • Organization ID (copanyId) - Organization ID under which the terminal is used.
  • Terminal ID (terminalId) - Terminal ID assigned to this terminal.
  • Terminal timezone code (timezone) - Local timezone what terminal should use.
  • Terminal currency code (currencyCodeNum) - Currency code used for transactions. This information is also provided through terminal EMV parameters.

The Terminal should store this information in the terminal's local storage as long as the terminal is registered under this organization. Changing of this information is only possible through terminal deregistration and new registration.

Dynamic data​

The Terminal should periodically call TPS Device API update endpoint for retrieving dynamic data updates.

The following data will be provided through this endpoint:

  • EMV configuration - TLV data for configuring EMV kernels.
  • Terminal keys — Secret keys and CA certificates needed for accepting EMV cards and sending EMV transactions to TPS.
  • Permanent stoplist — PAN ranges of the EMV cards that should be declined.
  • Deny list updates — EMV card tokens what should be declined.

The Terminal should store this data in the terminal's local storage and apply any updates received afterward. Secret keys should be stored in secure key storage.

Typically terminal needs the following two secret keys for operation:

  • SALT - Secret HMAC key used for card token generation
  • TTK or IPEK - Secret AES key used for encrypting the transaction data

Terminal secret keys are signed with Device Key Signing Key Private Key, and the terminal should use Device Key Signing Key Certificate (DKSK-CERT) for validating the signature. Terminal secret keys are encrypted with Device Key Encryption Key Public Key, and terminal should use Device Key Encryption Key Private Key (DKEK-PRIV) for decrypting them.